home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr05 / wrcpdl14.zip / RCPDLL.DOC < prev    next >
Text File  |  1995-01-17  |  12KB  |  289 lines
  1.   Winsock RCP.DLL                                    Version 1.4
  2.   Copyright 1994 Denicomp Systems
  3.   All rights reserved
  4.  
  5.   
  6.   DESCRIPTION
  7.   -----------
  8.   
  9.   Winsock RCP.DLL is a Microsoft Windows 3.1 Dynamic Link Library that
  10.   provides a Windows Sockets compatible function that allows you to copy files
  11.   over TCP/IP.  You can copy files from a Windows PC to a remote host, from
  12.   the remote host to your PC, or between two remote hosts.
  13.  
  14.   Winsock RCP.DLL provides most of the services of the "rcp" command found
  15.   on many Unix systems, including recursive copies.  It also includes the
  16.   ability to convert text files to the appropriate format for Unix or MS-DOS.
  17.  
  18.   The remote host must be a system running the rshd server process
  19.   (i.e. a Unix system).  You cannot copy files to another PC, for example.
  20.  
  21.   
  22.   REQUIREMENTS
  23.   ------------
  24.  
  25.   Winsock RCP.DLL requires a PC running Windows 3.1 or higher, a Windows
  26.   Sockets compatible TCP/IP stack, and any programming language that supports
  27.   calls to DLL functions, such as C or Visual Basic.
  28.  
  29.  
  30.  
  31.   =============================================================================
  32.  
  33.   FUNCTION: WinsockRCP
  34.  
  35.   Syntax:
  36.   -------
  37.  
  38.   C:
  39.   
  40.   int FAR PASCAL WinsockRCP (hwndParent, Title, Src, Dest, RecurFlag, AsciiFlag)
  41.   
  42.        HWND hwndParent;
  43.        LPSTR Title;
  44.        LPSTR Src;
  45.        LPSTR Dest;
  46.        int RecurFlag;
  47.        int AsciiFlag;
  48.   
  49.  
  50.   Visual Basic:
  51.  
  52.   Declare Function WinsockRCP Lib "RCP.DLL"
  53.                      (ByVal hWndParent As Integer,
  54.                       ByVal Title As String,
  55.                       ByVal Src As String,
  56.                       ByVal Dest As String,
  57.                       ByVal RecursiveFlag As Integer,
  58.                       ByVal AsciiFlag As Integer) As Integer
  59.  
  60.  
  61.   Usage:
  62.   ------
  63.   
  64.   The WinsockRCP function copies the Source to the Destination.  The
  65.   Source and Destinations are file specifications that can include a
  66.   user name, a host name, and a file name, which may include wildcard
  67.   characters, such as * and ?.
  68.  
  69.   Parameters:
  70.   -----------
  71.  
  72.   hwndParent:  The HWND of a window in your application.  The WinsockRCP 
  73.                function may produce diagnostic error messages using the
  74.                Windows MessageBox function.  This is used to specify the
  75.                "parent" window to the MessageBox function.  It may be NULL.
  76.   
  77.   Title:       The title of your application or some other title.  If any
  78.                diagnostic error messages are displayed using the Windows
  79.                MessageBox function, this will be used as the title of the
  80.                message box.
  81.   
  82.   Src:         The file or directory to copy.  See below for the format.
  83.  
  84.   Dest:        The destination of the file(s).  See below for the format.
  85.   
  86.   RecurFlag:   Specifies whether or not the copy should be recursive.  Use
  87.                a value of 0 if it is not recursive or 1 if it is.  A recursive
  88.                copy copies entire directory trees.
  89.   
  90.   AsciiFlag:   Specifies whether or not the copy should convert the file
  91.                to the proper text file format.  If the file is being copied
  92.                TO a remote host, CR/NL (ASCII 13/10) combinations are replaced
  93.                with one NL (ASCII 10).  If the file is being copied FROM a
  94.                remote host, NL's are replaced by CR/NL combinations.
  95.  
  96.                Use a value of 0 if the files are not to be converted or
  97.                a value of 1 if they are to be converted.
  98.  
  99.  
  100.   Source and Dest Specifications
  101.   ------------------------------
  102.  
  103.   Both the Source and Dest parameters must be of the following format:
  104.  
  105.        [[User@][Host:]]{File | Dir}
  106.  
  107.  
  108.   User@   (optional)  Specifies the user name to be used at the remote
  109.           host.  If this prefixes the Host: parameter, this user name
  110.           overrides the user name of the PC.
  111.  
  112.   Host:   Specifies the host name of the remote host.  This is not
  113.           required if the file or directory referenced is on the PC.
  114.           This host must be a system running the rshd server process.
  115.           That is, you cannot use the host name of another PC running
  116.           Windows or MS-DOS.
  117.  
  118.   File      Specifies the file name of the source or destination file.  You
  119.           may use wildcard characters to copy multiple source files.  You
  120.           may also specify multiple source files individually by separating
  121.           the names with spaces.
  122.  
  123.   Dir     Specifies the file name of the source or destination directory.
  124.           The source may be a directory only if you are using the recursive
  125.           copy option.  The destination must be a directory if you are
  126.           copying multiple files or copying recursively.
  127.  
  128.  
  129.  
  130.   Return Value:
  131.   -------------
  132.  
  133.   If WinsockRCP sucessfully copies all specified files, it will return zero.
  134.   
  135.   If WinsockRCP is not successful, it will return -1.  Note that if multiple
  136.   files are to be copied, it will return -1 if an error occurs on any of the
  137.   files.  WinsockRCP may have successfully copied files prior to the error
  138.   and depending on the problem, may continue to copy the remaining files.
  139.   
  140.   Notes:
  141.   ------
  142.  
  143.   A Host: must be specified for either the Source or Dest parameters, or
  144.   both.  You cannot use WinsockRCP to copy files locally; you will receive
  145.   an error if you try.
  146.  
  147.   Do not use the Host: parameter when referencing local files; this will
  148.   not work.
  149.   
  150.   The local user name is determined by first looking in the file WIN.INI
  151.   in the Windows directory.  If this file contains a section named "[RCP]"
  152.   and contains an entry named "User" in that section, the name specified
  153.   there will be used as the local user name.  For example, WIN.INI would
  154.   contain:
  155.  
  156.      [RCP]
  157.      User=joe
  158.  
  159.   If this appeared in WIN.INI, the local user name would be "joe" and
  160.   WinsockRCP would use this name at the remote host.
  161.  
  162.   If this section does not appear in WIN.INI, WinsockRCP uses the Computer
  163.   Name specified in the Windows for Workgroups Network Setup (found on the
  164.   Control Panel).  This name is converted to lowercase characters and
  165.   WinsockRCP uses this name at the remote host.  Therefore, if no user name is
  166.   specified in WIN.INI, the Computer Name of the PC must be set up as a
  167.   valid user on the remote host, in addition to being included in the
  168.   remote host's /etc/hosts.equiv file.
  169.  
  170.   (If you are not using Windows for Workgroups and your network does not
  171.   provide the services that Windows for Workgroups provides, you must use
  172.   WIN.INI to specify the user name or always use the User@ parameter.)
  173.  
  174.   If a full directory path is not specified for a remote host, the path
  175.   begins at the user's home directory.  That is, if the file/directory
  176.   name specified after the Host: parameter does not begin with a slash (/),
  177.   it is assumed to reference a file/directory in the user's home directory.
  178.  
  179.   For example, the file "joe@remhost:file.txt" refers to the file "file.txt"
  180.   in the home directory of the user "joe" on the host "remhost".
  181.  
  182.   Filenames may contain either slashes (/) or backslashes (\) as directory
  183.   separators, for either the host file/directory or file/directories on the
  184.   PC.  They will be converted to the appropriate separator.
  185.  
  186.   You can copy multiple files by using wildcard characters, such as * or ?.
  187.  
  188.   The Source and Dest parameters may include only ONE file specification
  189.   each.  That is, you CANNOT specify multiple source files by separating
  190.   them with spaces as you can with the "rcp" command.  To copy multiple
  191.   individual filenames (that cannot be specified using wildcards or using
  192.   a recursive copy), you must call WinsockRCP for each file.
  193.  
  194.   If you copy multiple source files with wildcard characters, the destination
  195.   the destination must be a directory.
  196.  
  197.   Note that a colon (:) terminates the host name.  This causes a problem
  198.   when filenames on the PC require a drive letter (e.g. A:).  If a file
  199.   name specification begins with one character between A and Z and is
  200.   followed by a colon (:), WinsockRCP will interpret this as a drive letter
  201.   instead of a host name.  This means that WinsockRCP cannot handle one
  202.   character host names.
  203.  
  204.   The destination cannot contain only a drive specification (e.g. A:).  It
  205.   must also include a filename or a directory name.  If the destination is
  206.   the current directory on the drive, use "." (e.g. A:.).
  207.  
  208.   Using the ASCII conversion option to transfer files TO the remote host will
  209.   slow the operation of Winsock RCP.DLL somewhat because it must read each
  210.   file twice.  It reads the file once to calculate the new translated file
  211.   size, then reads it again to transfer the data.  This is because the RCP
  212.   protocol requires that the exact file size be transmitted before the actual
  213.   data in the file is sent.  Without the conversion option, the file size can
  214.   be found by examining the file's directory entry, but with the conversion
  215.   option, the file's contents must be examined to determine the size after
  216.   CR/NL combinations are replaced with NL.
  217.  
  218.   The ASCII conversion option will also slow Winsock RCP when when
  219.   transferring files FROM the remote host, but only slightly.
  220.  
  221.   If transmission speed is critical, consider using utilties to translate the
  222.   text files after they are transferred.
  223.  
  224.  
  225.   SECURITY 
  226.   --------
  227.   
  228.   The local user name determines the file access privileges WinsockRCP
  229.   uses at that remote host.  This name also determines the ownership and
  230.   access modes of the destination file or files.  The remote host allows
  231.   access if one of the following conditions is satisfied:
  232.   
  233.   * The name of the local host is listed as an equivalent host in the
  234.     /etc/hosts.equiv file on the remote host.
  235.  
  236.     The method of specifying the local host name is determined by the
  237.     particular TCP/IP stack you are using.
  238.     
  239.   * If the local host is not in the /etc/hosts.equiv file, the user's home
  240.     directory on the remote host must contain a .rhosts file that lists the
  241.     local host and local user name.
  242.   
  243.   * The user's login on the remote host does not require a password.
  244.  
  245.   The .rhosts file in the user's home directory must be owned by either
  246.   the user specified or "root", and only the owner should have read and write
  247.   access.
  248.  
  249.  
  250.   EXAMPLE
  251.   -------
  252.  
  253.    For a full working example of the WinsockRCP function in C, see the CRCP
  254.    program included in the distribution.
  255.  
  256.    For a full working example of the WinsockRCP function in Visual Basic,
  257.    see the VRCP program included in the distribution.  This is the source
  258.    to the Visual RCP program included with Winsock RCP and RSH.
  259.  
  260.  
  261.    // This example copies the file "system.doc" in the user tom's home
  262.    // directory on the host "remhost" to the directory "\doc" on the PC
  263.  
  264.        int result;
  265.  
  266.        LPSTR rtitle = "Winsock RCP DLL Sample";
  267.        LPSTR src = "tom@remhost:system.doc"
  268.        LPSTR dest = "\\doc"
  269.  
  270.        result = WinsockRCP(hWndMain,rtitle,src,dest,0,0);
  271.  
  272.        if (result < 0)
  273.          MessageBox(hWndMain,Remote Copy Was Not Successful",rtitle,MB_OK);
  274.        else
  275.          MessageBox(hWndMain,Remote Copy Was Successful",rtitle,MB_OK);
  276.  
  277.  
  278. SUPPORT
  279. -------
  280.  
  281. Support is available via U.S. Mail and Compuserve/Internet:
  282.  
  283. Denicomp Systems
  284. P.O. Box 731
  285. Exton, PA  19341
  286.  
  287. Compuserve: 71612,2333
  288. Internet:   71612.2333@compuserve.com
  289.